fix(wslc): clarify WSL runtime prerequisite - #656
Open
huzaifa-d wants to merge 2 commits into
Open
Conversation
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR clarifies WSLC prerequisite failures when WslcCanRun reports missing components, aligning runtime requirements (WSL runtime package minimum) with the getting-started documentation and adding a regression test for the new message.
Changes:
- Add a helper to produce a more specific WSLC prerequisite error when
WslcCanRunreportsWslPackagemissing, and add a unit test covering the message contents. - Update the WSLC getting-started guide to consistently document the minimum WSL runtime version (2.8.0+) and clarify that
wslcsdk.dllis a separate dependency.
Show a summary per file
| File | Description |
|---|---|
| src/backends/wslc/common/src/wsl_container_runner.rs | Improves prerequisite failure messaging from WslcCanRun and adds a unit test for the updated message. |
| docs/wsl/wsl-container-getting-started.md | Updates prerequisite and troubleshooting documentation to consistently state the WSLC minimum WSL runtime version and separate SDK DLL requirement. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 2
- Review effort level: Low
MGudgin
reviewed
Jul 17, 2026
| } | ||
|
|
||
| fn wslc_prerequisite_error(missing: WslcComponentFlags) -> String { | ||
| if missing as u32 & WslcComponentFlags::WslPackage as u32 != 0 { |
Member
There was a problem hiding this comment.
WslcComponentFlags is a fieldless repr(u32) enum, but wslcsdk.h declares it as combinable flags. WslcCanRun can therefore return 3 when both components are missing, which is not a valid Rust enum discriminant and causes undefined behavior when read here. Please represent this FFI type as a transparent integer-backed bitmask and add coverage for combined values.
MGudgin
reviewed
Jul 17, 2026
MGudgin
reviewed
Jul 17, 2026
MGudgin
requested changes
Jul 17, 2026
microsoft-github-policy-service
Bot
added
the
Needs-Author-Feedback
MGudgin
approved these changes
Jul 23, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f46e1b1d-d428-4d1b-b9c3-b83ca7b35ec2
- Branch remediation guidance by missing component: VirtualMachinePlatform now tells the user to enable the Windows optional feature instead of incorrectly suggesting a WSL update, per review feedback (updating WSL does not enable Virtual Machine Platform). - Standardize on 'WSLC runtime unavailable' wording across code and docs (was inconsistent with 'runtime not available' in some places). - Add table-driven tests covering WslPackage, VirtualMachinePlatform, their combined value, and SdkNeedsUpdate, asserting the version and remediation guidance selected for each case. - Align remaining docs mentions in wsl-container-support-plan.md with the same wording. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
huzaifa-d
force-pushed
the
huzaifa-d-investigate-issue-553
branch
from
July 28, 2026 19:06
e0681ed to
a30461e
Compare
Contributor
There was a problem hiding this comment.
Review details
Comments suppressed due to low confidence (4)
src/backends/wslc/common/src/wsl_container_runner.rs:343
WSLC_COMPONENT_FLAG_SDK_NEEDS_UPDATEis not handled here. When it is the only bit, the message merely says to ensure the SDK is installed; when combined with another bit, SDK guidance disappears entirely. Add a dedicated branch with an actionable SDK-update remedy, leaving the generic fallback only for unknown flags.
if guidance.is_empty() {
guidance.push("ensure WSL2 and the WSLC SDK are installed".to_string());
docs/wsl/wsl-container-getting-started.md:303
- This troubleshooting row omits the
SdkNeedsUpdatecondition thatWslcGetMissingComponentscan report. Add the outdated/incompatible WSLC SDK case and its actionable remedy; otherwise users receiving that named component still cannot resolve the error from this guide.
| `WSLC runtime unavailable` | WSL runtime package is missing, older than 2.9.3, or the Virtual Machine Platform optional component is disabled | Update WSL with `wsl --update --pre-release`, verify the installed version with `wsl --version`, and enable the Virtual Machine Platform optional component if required. The WSLC SDK DLL is a separate dependency and does not replace the WSL runtime package. |
docs/wsl/wsl-container-getting-started.md:14
- This newly added row duplicates the identical Windows 11 prerequisite immediately above it. Remove the duplicate so the table lists each requirement once.
This issue also appears on line 303 of the same file.
| **Windows 11** | Required for WSL2 and the WSLC SDK |
src/backends/wslc/common/src/wsl_container_runner.rs:340
- This contradicts the PR description, which says the error should direct users to WSL 2.8.1+ and the stable
wsl --updatecommand. Requiring 2.9.3 from the pre-release channel is materially different. Confirm the actual runtime floor and align this message, its tests, the getting-started guide, and the PR description.
This issue also appears on line 342 of the same file.
.push("install WSL 2.9.3 or newer and run `wsl --update --pre-release`".to_string());
- Files reviewed: 3/3 changed files
- Comments generated: 0 new
- Review effort level: Medium
MGudgin
approved these changes
Jul 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📖 Description
Clarifies the WSLC error when WSL is too old. The error now points users to WSL 2.8.1+ and
wsl --update; the getting-started guide is aligned.🔗 References
Resolves #553
🔍 Validation
cargo fmt --all -- --checkcargo test -p wslc_common(45 passed)✅ Checklist
Cargo.lock, thedependency-feed-checkcheck passes📋 Issue Type